通用图表标记属性 (ChartMarkProps)#

ChartMarkProps 用于配置图表中的每一个 mark（例如柱状图的 BarMark、折线图的 LineMark 等），提供一系列通用的修饰属性，支持设置样式、符号、位置、注解、变换等内容。该类型可用于 BarChart、LineChart、AreaChart 等组件的 marks 属性中。

一、样式修饰#

foregroundStyle#

设置图表内容的填充颜色或样式。

• 类型：ShapeStyle | DynamicShapeStyle

• 示例：

  1foregroundStyle: "systemGreen"

opacity#

设置透明度，取值范围为 0.0 ~ 1.0。

• 类型：number

• 示例：

  1opacity: 0.5

cornerRadius#

设置图形的圆角半径，常用于柱状图或胶囊图。

• 类型：number

• 示例：

  1cornerRadius: 8

lineStyle#

设置线条样式，适用于折线图或路径图。

• 类型：StrokeStyle

• 结构：

  1{
  2  lineWidth?: number
  3  lineCap?: 'butt' | 'round' | 'square'
  4  lineJoin?: 'bevel' | 'miter' | 'round'
  5  mitterLimit?: number
  6  dash?: number[]
  7  dashPhase?: number
  8}

• 示例：

  1lineStyle: {
  2  lineWidth: 2,
  3  lineCap: "round",
  4  dash: [4, 2]
  5}

interpolationMethod#

设置线图或面积图的插值方式（曲线连接方式）。

• 类型：ChartInterpolationMethod

• 可选值： "cardinal"、"catmullRom"、"linear"、"monotone"、"stepCenter"、"stepEnd"、"stepStart"

• 示例：

  1interpolationMethod: "catmullRom"

alignsMarkStylesWithPlotArea#

样式是否与绘图区对齐。

• 类型：boolean

• 示例：

  1alignsMarkStylesWithPlotArea: true

二、符号设置（用于折线图或散点图）#

symbol#

设置标记符号的形状，或使用自定义视图作为标记。

• 类型：ChartSymbolShape | VirtualNode

• 可选值： "circle"、"square"、"triangle"、"diamond"、"cross"、"plus"、"asterisk"、"pentagon"

• 示例：

  1symbol: "triangle"

symbolSize#

设置符号大小，可以是单一数值或包含宽高的对象。

• 类型：number | { width: number; height: number }

• 示例：

  1symbolSize: 18
  2// 或
  3symbolSize: { width: 16, height: 16 }

三、注解设置#

annotation#

为某个 mark 添加注释视图，并可设置位置、对齐、间距及溢出处理策略。

• 类型：VirtualNode | { position?, alignment?, spacing?, overflowResolution?, content }

• 示例：

  1annotation: {
  2  position: "top",
  3  alignment: "center",
  4  spacing: 4,
  5  overflowResolution: {
  6    x: "fit",
  7    y: "padScale"
  8  },
  9  content: <Text>注解</Text>
  10}

AnnotationPosition 注解位置#

用于控制注解视图相对于 mark 的定位位置。

• 类型：字符串
• 可选值： "automatic"、"top"、"topLeading"、"topTrailing"、 "bottom"、"bottomLeading"、"bottomTrailing"、 "leading"、"trailing"、"overlay"

AnnotationOverflowResolutionStrategy 溢出处理策略#

用于处理注解超出图表边界时的排版策略。

• 可选值：

  • "automatic"：自动选择合适的策略
  • "fit"：自动调整位置以适配边界
  • "fitToPlot"：限制在绘图区范围内
  • "fitToChart"：限制在整个图表范围内
  • "fitToAutomatic"：自动选择图表或绘图区
  • "padScale"：扩展坐标范围为注解留出空间
  • "disabled"：不处理溢出，允许剪裁

四、图形变换效果#

clipShape#

设置图形裁剪区域的形状。

• 类型："rect"、"circle"、"capsule"、"ellipse"、"buttonBorder"、"containerRelative"

• 示例：

  1clipShape: "capsule"

shadow#

为 mark 添加阴影。

• 类型：

  1{
  2  color?: string
  3  radius: number
  4  x?: number
  5  y?: number
  6}

• 示例：

  1shadow: {
  2  color: "systemGray",
  3  radius: 4,
  4  x: 2,
  5  y: 2
  6}

blur#

添加模糊效果，数值越大模糊越强。

• 类型：number

• 示例：

  1blur: 5

zIndex#

控制 mark 在图层中的显示顺序。

• 类型：number

• 示例：

  1zIndex: 10

offset#

为 mark 设置偏移量，可控制其在 X/Y 轴上的位置偏移。

• 类型支持以下形式：

  • { x, y }
  • { x, yStart, yEnd }
  • { xStart, xEnd, y }
  • { xStart, xEnd, yStart, yEnd }

• 示例：

  1offset: { x: 10, y: -5 }

五、数据绑定修饰（xxxBy）#

通过绑定数据字段实现动态设置样式或位置，不能与相同功能的静态属性同时使用。

foregroundStyleBy#

根据数据字段动态设置填充样式。

• 类型：string | number | Date | { value, label }

• 示例：

  1foregroundStyleBy: {
  2  value: item.color,
  3  label: "颜色"
  4}

lineStyleBy#

根据数据字段动态设置线条样式。

• 示例：

  1lineStyleBy: {
  2  value: item.type,
  3  label: "线型"
  4}

positionBy#

设置 mark 的位置和在图表坐标轴上的作用方向。

• 类型：

  1{
  2  value: string | number | Date
  3  label?: string
  4  axis: 'horizontal' | 'vertical'
  5  span?: MarkDimension
  6}

• 示例：

  1positionBy: {
  2  value: item.category,
  3  axis: "horizontal",
  4  span: {
  5    type: "ratio",
  6    value: 0.8
  7  }
  8}

MarkDimension 标记尺寸控制#

用于控制 mark 在轴向上的占用空间或尺寸。

• 类型："automatic" 或：

  1{
  2  type: "inset" | "fixed" | "ratio"
  3  value: number
  4}

• 含义说明：

  • "automatic"：系统自动决定尺寸
  • "inset"：根据设定的边距减少宽度或高度
  • "fixed"：固定的像素尺寸
  • "ratio"：根据比例占据坐标轴步长（范围 0~1）

symbolBy#

根据数据字段动态设置符号形状。

• 示例：

  1symbolBy: {
  2  value: item.category,
  3  label: "类型"
  4}

symbolSizeBy#

根据数据字段动态设置符号大小。

• 示例：

  1symbolSizeBy: {
  2  value: item.count,
  3  label: "数量"
  4}

示例：分组柱状图#

1<BarChart
2  marks={data.map(item => ({
3    label: item.type,
4    value: item.count,
5    positionBy: {
6      value: item.color,
7      axis: "horizontal"
8    },
9    foregroundStyleBy: item.color,
10    cornerRadius: 8
11  }))}
12/>